Add a section to the PR guide on how to write good titles and descriptions#1845
Add a section to the PR guide on how to write good titles and descriptions#1845sirosen wants to merge 3 commits into
Conversation
Add a short section to the PR guide which covers good titles and descriptions, at a summary level. The priority here is (in presentation order): - explain the rationale / why we care - demonstrate how a PR title should look - give some hint as to what a good description will look like Explaining how to write good technical prose for a PR description is considered out of scope, which limits the content of the PR description section.
Documentation build overview
3 files changed± getting-started/index.html± versions/index.html± getting-started/pull-request-lifecycle/index.html |
| The title should be a sentence or phrase in the imperative which says what the | ||
| pull request does in short form. It should start with ``gh-NNNNNN:``, for pull | ||
| requests which close open issues. | ||
| For example, ``gh-12345: Fix bug when spam module is served with eggs``. |
There was a problem hiding this comment.
Some of this is duplicated in the Submitting section. To me, the Making good PRs section seems like a checklist about the change itself, not a checklist for the PR on GitHub.
I think, looking at the (albeit quite terrible) flow, this section is too early (the following section here is about pre-submission things, for example), and can be merged with the duplicated content in Submitting.
There was a problem hiding this comment.
I can see what you're getting at. I think I'd like to make further changes to "Submitting" -- I don't think it's quite right in scope right now -- but not right now.
I'd like to move this section down and deduplicate a bit. I'll try to be surgical in my changes, but avoiding repetition strikes me as a good reason to increase the scope of my changes.
There was a problem hiding this comment.
I moved it and think the result is "okay".
To make it really great we'll need to make more changes than I can reasonably fit in here. 🙂
Co-authored-by: Stan Ulbrych <[email protected]>
Give this section a referenceable label, and place it in the "Submitting" section rather than "Writing good pull requests". Keep the content largely the same, but add a new trailing sentence to note that `#NNNNN` syntax can link issues. This replaces a note from "Submitting" that was mostly redundant with the new section.
2 participants
Add a short section to the PR guide which covers good titles and descriptions, at a summary level.
The priority here is (in presentation order):
Explaining how to write good technical prose for a PR description is considered out of scope, which limits the content of the PR description section.
Resolves #931
Supersedes prior PRs, and therefore